This is the readme file from the distribution.

Download the distribution (gzipped tar file)

June 14, 1996

Fred Dalrymple


Overview
========

This directory contains all pieces of the docbook-to-man tool -- a
batch converter that transforms UNIX-style manpages from the DocBook
SGML DTD into nroff/troff -man macros.


Acknowledgements
================

The following companies generously funded the development of this public
tool as part of the CDE/Motif Project under the auspices of the Open
Software Foundation:

    Hewlett-Packard Company
    International Business Machines Corp.
    Sun Microsystems, Inc.
    Novell, Inc.
    Digital Equipment Corp.
    Fujitsu Limited
    Hitachi, Ltd.


SETUP NOTES
===========

This tool presumes that nsgmls and the DocBook DTDs have been installed
into "default" places.  Mainly, this means where the DTD files are
expected to be found (/usr/local/sgmls, /usr/local/sgmls/Davenport/dtd).
If you've installed them elsewhere, please modify the paths at the top
of cmd/docbook-to-man.sh before installing this tool (or, change it and
reinstall it).


INSTALLATION
============

This tool installs binaries for the instant and docbook-to-man programs
into /usr/local/bin, and the "transpec" into /usr/local/lib/tpt.  It is
assumed that /usr/local and /usr/local/lib exist, but the
Transpec/Makefile will attempt to create /usr/local/lib/tpt if it does
not already exist.  You must have permissions to write into /usr/local/bin
and /usr/local/lib to install these tools.

Assuming you've made and changes as noted in "SETUP NOTES" above, you
should be able to install this tool by issuing a "make install" from
the the current directory (the one containing this README file).
Generated binaries can be cleaned up from the source directories by
issuing a "make clobber".

The documentation in Doc/ is not installed automatically, you should
copy the files named Doc/instant.1 and Doc/transpec.1 into the proper
place (eg, /usr/local/man/man1) if you want to make them available online.



Components of the Tool
======================

User-level command:	docbook-to-man

	A new shell command that runs the low-level components to translate
	a single DocBook SGML document instance (whose document element is
	) into pretty-much vanilla -man macros, with tables
	rendered in tbl.

SGML parsing engine:    nsgmls (or sgmls)

	** not included in this package -- see ftp://ftp.jclark.com/pub/sp **

	The nsgmls or sgmls tool is called to parse a DocBook 
	instance and generate ESIS which is the input to the instant
	program.

Converter engine:	instant

	A tool originally developed at OSF (by John Bowe) but appearing
	here in significantly enhanced form (work performed by John
	Lavagnino, Carl Scholz, and particularly Fred Dalrymple).  The
	most significant enhancement is probably support for CALS tables
	(which DocBook uses).  Sorry, only the CALS -> tbl functionality
	works in this version.

Converter script:	docbook-to-man.ts

	The instant script which drives the mapping between SGML and -man.

DocBook DTD:		docbook.cat, docbook.dcl, docbook.dtd

	The tool supports DocBook V 2.4.1.

	** not included in this package -- see
	   ftp://ftp.ora.com/pub/davenport/docbook/docbk241.tar.Z **



KNOWN DEFICIENCIES
==================

 1. The current transpec generates \fP to return to a previous font,
    yet there may be nested font changes.  It is possible that this
    script will generate two \fPs in a row, returning the font to
    not the original, but the "inner" font.  The transpec with the
    "-PUSHPOP" name in the Transpec source directory is some initial
    work to resolve this problem, but it has other problems..

 2. There are some CALS table features which aren't implemented (yet).
    Including tables within tables ().

 3. Numbered lists use an indent of 6 characters, while indented
    paragraphs (eg, a second  within an 
    ) will generate a 10 character indent.  Indents should
    be made consistent.

 4. The graphic inclusion is untested because I don't own a real
    Documentor's Workbench (and the code for generating the graphic
    include doesn't seem to work with Linux). 



BUG POLICY
==========

I would like to hear of any problems, improvements, or suggestions.
This tool will continue to be enhanced.  Significant improvements
will appear in the FTP-able version.  However, there is no guarantee
of turnaround time for problem reports...

Please send correspondence to fld@veloce.com